欢迎文件

Web 应用程序开发人员可以在 Web 应用程序部署描述文件中定义一个称为欢迎文件的局部 URI 有序列表。在 Web 应用程序部署描述文件模式中描述了部署描述文件中欢迎文件列表的语法。

这种机制的目的是,当一个对应到 WAR文件中一个目录条目的请求 URI没有映射到一个 Web 组件时,允许部署者为容器用于添加 URI 指定局部URI 有序列表。这种请求被认为是有效的局部请求。

通过下面常见的例子来明确这种用法的便利:可以定义‘index.html’欢迎文件,以便像请求 URL host:port/webapp/directory/,其中‘directory’是 WAR 文件中的一个不能映射到 servlet 或 JSP 页面的条目,以下面的形式返回给客户端:‘host:port/webapp/directory/index.html’。

如果 Web 容器接收到一个有效的局部请求,Web 容器必须检查部署描述文件中定义的欢迎文件列表。欢迎文件列表是一个没有尾随或前导/的局部URL 有序列表。Web 服务器必须把部署描述文件中按指定顺序的每个欢迎文件添加到局部请求,并检查 WAR 文件中的静态资源是否映射到请求 URI。如果没有找到匹配的,Web 服务器必须再把部署描述文件中按指定顺序的每个欢迎文件添加到局部请求,并检查 servlet 是否映射到请求 URI。 Web 容器必须将请求发送到 WAR 文件中第一个匹配的资源。容器可使用转发、重定向、或容器指定的机制将请求发送到欢迎资源,这与直接请求没有什么区别。

如果按上述的方式没有找到匹配的欢迎文件,容器可能会使用它认为合适的方式处理该请求。对于有的配置来说,这可能意味着返回一个目录列表,对其他配置来说可能返回一个404响应。

考虑一个 Web 应用程序:

  • 部署描述文件列出了以下的欢迎文件。
    1. <welcome-file-list>
    2. <welcome-file>index.html</welcome-file>
    3. <welcome-file>default.jsp</welcome-file>
    4. </welcome-file-list>
  • WAR 文件中的静态内容如下
    1. /foo/index.html
    2. /foo/default.jsp
    3. /foo/orderform.html
    4. /foo/home.gif
    5. /catalog/default.jsp
    6. /catalog/products/shop.jsp
    7. /catalog/products/register.jsp
  • 请求URI /foo将被重定向到URI /foo/。
  • 请求URI /foo/将返回/foo/index.html的。
  • 请求URI /catalog将被重定向到URI /catalog/。
  • 请求URI /catalog/将返回/catalog/default.jsp。
  • 请求URI /catalog/index.html将导致404未找到错误。
  • 请求URI /catalog/products将重定向到URI /catalog/products/。
  • 请求URI /catalog/products/将被传递给“默认”的 servlet(如果有默认的 servlet 的话)。如果没有映射到“默认”的 servlet,请求可能会导致一个404未找到错误,可能会导致一个包括 shop.jsp 和 register.jsp目录列表,或可能导致容器定义的其他行为。请参见12.2节,“映射规范”定义的“默认” servlet。
  • 所有上述的静态内容都可以打包到 JAR 文件的 META-INF/resources目录中。这个 JAR 文件可以放到 Web 应用的 WEB-INF/lib 目录下。